The World of Computer Software

home *** CD-ROM | disk | FTP | other *** search

/ The World of Computer Software / The World of Computer Software.iso / ultra250.zip / UW_HELP4.HLP < prev next >

Wrap

Text File | 1992-11-03 | 27KB | 636 lines

`co(4,7);─────────────────────── /// Rectangle Functions ──────────────────────────────`co(); ┌──────────────────────────────────────────────────────────────────────────┐ │ `keyword(set_rect,/// set_rect); `keyword(is_rect_equal,/// is_rect_equal); `keyword(rect_overlap,/// rect_overlap); │ │ `keyword(offset_rect,/// offset_rect); `keyword(col_row_inrect,/// col_row_inrect); │ └──────────────────────────────────────────────────────────────────────────┘ The UltraWin library uses the structure RECT to handle information dealing with rectangular sections of the screen, as in the WINDOW structure. Included are functions to define the rectangle, check to see if one rectangle overlaps another, and several other routines that you may wish to utilize in your program. `co(10,1);/// set_rect`co(); `keyword(source,[UW_WIN.C]~set_rect); Takes the variable of type RECT passed by pointer, and sets the upper left corner and lower right corner to the coordinates passed as integers. Prototype: void set_rect(RECT *rectp, int x1, int y1, int x2, int y2); Parameters: `co(11,1); RECT *rectp;`co(); A pointer to the rectangle variable. `co(11,1); int x1, y1, x2, y2`co(); The coordinate pair for the upper left corner (x1,y1) and the lower right corner (x2,y2) of the rectangle. Usage: RECT r; ... set_rect( &r, 10, 10, 20, 20 ); `co(10,1);/// is_rect_equal`co(); `keyword(source,[UW_WIN.C]~is_rect_equal); Checks to see if the two rectangles are the same. Prototype: int is_rect_equal(RECT *r1, RECT *r2); Parameters: `co(11,1); RECT *r1, *r2;`co(); Pointers to the two rectangles to compare. Usage: RECT r1, r2; ... if (is_rect_equal( &r1, &r2 )) {} `co(10,1);/// rect_overlap`co(); `keyword(source,[UW_WIN.C]~rect_overlap); Reports on the relationship between two rectangles. This function will return the status as one of the following (defined in UW.H): 1) FIRST_ENCLOSED The first rectangle is enclosed within the second. 2) SECOND_ENCLOSED The second rectangle is enclosed within the first. 3) OVERLAP The rectangles overlap. 4) NO_OVERLAP The rectangles do not overlap. Prototype: int rect_overlap(RECT *r1, RECT *r2); Parameters: `co(11,1); RECT *r1, *r2;`co(); The two rectangles whose relationship to find. Usage: RECT r1, r2; int status; ... status = rect_overlap( &r1, &r2 ); `co(10,1);/// offset_rect`co(); `keyword(source,[UW_WIN.C]~offset_rect); Moves the rectangles coordinates by a fixed positive or negative amount in both the x (column) and y (row) direction. Prototype: void offset_rect(RECT *rectp, int col, int row); Parameters: `co(11,1); RECT *rectp;`co(); A pointer to the rectangle variable. `co(11,1); int col, row`co(); The offsets to add to the rectangle's coordinates. Usage: RECT r; ... offset_rect( &r, 5, -4 ); `co(10,1);/// col_row_inrect`co(); `keyword(source,[UW_WIN.C]~cr_inrect); Checks to see if a particular location is inside (or on the border of) the rectangle passed. Prototype: int col_row_inrect(int col, int row, RECT *rectp); Parameters: `co(11,1); int col, row`co(); The coordinate to check. `co(11,1); RECT *rectp;`co(); A pointer to the rectangle. Usage: RECT r; ... if (col_row_inrect( 5, 5, &r )) {} `co(4,7);──────────────────────────── /// Data Entry ──────────────────────────────────`co(); ┌──────────────────────────────────────────────────────────────────────────┐ │ `keyword(wn_gets,/// wn_gets); `keyword(Masks/Templates,/// Masks/Templates); │ │ `keyword(Validation Chars,/// Validation Chars); `keyword(Strip Mask Option,/// Strip Mask Option); │ │ `keyword(wn_gets_ll,/// wn_gets_ll); │ └──────────────────────────────────────────────────────────────────────────┘ One of the most flexible of all functions in the UltraWin library is wn_gets. With this one function you can have the user enter dates, times, prices, strings, and any other type with full control over every character entered! UltraWin versions 2.00 and up add an even more powerful lower level function now called by wn_gets to enhance the capabilities even further. Full compatibility is maintained. The new function called wn_gets_ll has added the capability to uppercase the first character of each word, strip the mask completely, only strip the end, or not strip at all. It can also get input right-to-left, clear an input on the first non-keypad keypress, and exit when the last character in the input is entered, saving an extra <Enter> keypress. Furthermore it can allow the user to input a string longer than the display width of the field and will scroll within this region automatically! It can also display arrows to show the user that the string has data to the left or right of the current display field. If this isn't enough for you, we've added the ability to call your own validation function for every character entered in wn_gets_ll. This allows you to validate the user's input "as it happens", and enhance wn_gets_ll. A new wn_gets_ll hook added in version 2.10 allows both pre and post processing, as well as the ability to modify the event itself, giving you the ability to translate keys. See also `keyword(set_validation_func,/// set_validation_func);. `co(10,1);/// wn_gets`co(); `keyword(source,[UW_ENTRY.C]~wn_gets); Gets input from the user according to the restrictions of the mask and template strings in the window passed by pointer. This function will pass back the input either with the mask characters included in the string, or stripped out. A -1 is returned if the mouse is clicked off of the string, and one of the values KEY_UP, KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC, KEY_ENTER, KEY_TAB or KEY_SHFT_TAB (defined in UW_KEYS.H) is returned if pressed. Read about the mask and template strings for more information. Prototype: int wn_gets( char *str, char *mask, char *template, uchar m_att, int strip_mode, WINDOW *wnp ); Parameters: `co(11,1); char *str`co(); The string to be returned by the function. `co(11,1); char *mask`co(); The mask string. `co(11,1); char *template`co(); The template string. `co(11,1); uchar m_att`co(); The attribute (colors) to use when displaying the string. `co(11,1); int strip_mode`co(); Set to 1 (STRIP_ON) to strip mask characters out of result, or set to 0 (STRIP_OFF) for full mask and result. `co(11,1); WINDOW *wnp;`co(); A pointer to the window in which entry is to take place. Usage: WINDOW *wnp; int result; char s[80]; ... result = wn_gets( s, "(___)-___-____", "### ### ####", wnp->att, STRIP_ON, wnp); `co(10,1);/// Masks/Templates`co(); The wn_gets function requires you to specify two important strings to perform its magic. These are the mask and template strings. The mask string gives you the flexibility of displaying textual information inside the area to be typed by the user. The mask characters are displayed in each position of the string that does not have text. The template string is essentially a string containing validation characters. Before a character is entered into the string, the wn_gets function compares the typed character with the template to see if the character is valid. In addition, the template can be used to force an uppercase or lowercase character without having the user touch the CapsLock or Shift keys. When combined, the mask and template strings give you great flexibility. The following are just a few examples with explanations of what they accomplish: mask = "________" Enter an 8 character string, where all tplt = "AAAAAAAA" characters must be alphanumeric. mask = "________" Enter an 8 character string, where tplt = "********" anything typed is valid. mask = "________" Enter an 8 character string, where the tplt = "Uaaaaaaa" first character is converted to uppercase, and the rest must be alpha. mask = "________" Enter an 8 character string, where all 8 tplt = "uuuuuuuu" characters must be typed in uppercase. mask = "(___) ___-____" Enter a 14 character string, where only tplt = " ### ### ####" numbers can be typed at the _ positions. `co(10,1);/// Validation Chars`co(); Validation characters are simply characters that are valid to put in your templates. The following is a list of the validation characters along with their effect. Validation Char Effect --------------- ----------------------------------------------- '#' Allows only a digit to be entered. '9' Allows digits, '+', '-', '.', 'E', and 'e'. 'X' Allows only a hexidecimal digit to be entered. 'u' Allows only upper case letters to be entered. 'l' Allows only lower case letters to be entered. 'U' Converts to upper case, even if typed as lower. 'L' Converts to lower case, even if typed as upper. 'A' Allows only alphanumeric characters and <space>. 'a' Allows only alpha characters and <space>. 'Y' Allows only boolean Y/N. 'T' Allows only boolean T/F. 'B' Allows only boolean Y/N or T/F. '*' Allows any characters. `co(10,1);/// Strip Mask Option`co(); This parameter to the wn_gets function gives you the option to have wn_gets either format the string with the mask characters intact, or strip out the mask characters. This can best be demonstrated as follows: mask = "(___) ___-____" tplt = " ### ### ####" When wn_gets is called with these parameters, and a phone number is entered, the display looks like this: (123) 456-7890 Very simply, if the strip mask option is not used, then this string is what is returned by the function (mask intact). However, if the strip mask option is used, then the returned string would be: 1234567890 with no mask characters left, only what the user typed! By utilizing this parameter in appropriate places you can save yourself a considerable amount of work. `co(10,1);/// wn_gets_ll`co(); `keyword(source,[UW_ENTRY.C]~wn_gets_ll); Has the same capabilities as wn_gets and more. Wn_gets_ll has the capability to uppercase the first char of each word, strip the mask completely, only strip the end, or not strip at all. Right-to-left input, clear entry on first key, and auto-return is also supported. The function will also allow the user to input a string longer than the display width of the field and will scroll within this region automatically. It can also display arrows to show the user that the string has data to the left or right of the current display field. We've added the ability to call your own validation function for every character entered in wn_gets_ll. This allows you to validate the user's input "as it happens", and customize the validation routine. See `keyword(set_validation_func,/// set_validation_func); for more information. Starting with version 2.10 we've added a powerful hook into this function that is called on entry, exit, and on every keypress. It is similar to the validation function except that wn_gets_ll expects a return key value from the function, giving the hook the ability to translate keystrokes. See `keyword(set_gets_hook,/// set_gets_hook); for more details. Prototype: int wn_gets_ll( char *str, char *mask, char *template, uchar m_att, int flags, int disp_width, WINDOW *wnp ); Parameters: `co(11,1); char *str`co(); The string to be returned by the function. `co(11,1); char *mask`co(); The mask string. `co(11,1); char *template`co(); The template string. `co(11,1); uchar m_att`co(); The attribute (colors) to use when displaying the string. `co(11,1); int flags`co(); `co(15,1);G_STRIP`co(); strips the entire mask from the string. * 12/04/91 = 120491, (432)-555-3421 = 4325553421 `co(15,1);G_STRIP_END`co(); strips the end of the string only. * John Doe____ = John Doe `co(15,1);G_UP_FST_CHAR`co(); convert the first letter of each word to uppercase, forcing all others to lowercase. * james elder II = James Elder Ii `co(15,1);G_UP_FST_CHAR2`co(); convert the first letter of each word to uppercase, leaving all others unchanged. * james elder II = James Elder II `co(15,1);G_ARROW`co(); displays left and right arrows if display width is less than field width. NOTE: This requires an additional screen/window space before and after the field. `co(15,1);G_VALIDATE`co(); call the validation function set by `keyword(set_validation_func,/// set_validation_func); `co(15,1);G_RIGHT_TO_LEFT`co(); gets input from the right side of the string. `co(15,1);G_CLEAR_ON_FIRST`co(); clears the entry string when the first valid non-keypad key is pressed. `co(15,1);G_EXIT_ON_FILL`co(); returns when the last character in the entry is typed, saving the user an <Enter> keypress. `co(15,1);G_MOVE_TO_END`co(); moves to the end of the field on entry. This is the equivalent of hitting <End>. `co(11,1); int disp_width`co(); The number of characters to display. If less than the length of the input field, the display field will scroll. `co(11,1); WINDOW *wnp;`co(); A pointer to the window in which entry is to take place. Usage: WINDOW *wnp; int result; char s[80]; ... /*---- strip mask, convert first character of each word to uppercase, -----*/ /*------- and only display 6 characters, using arrows to show more --------*/ result = wn_gets_ll( s, "______________", "AAAAAAAAAAAAA", wnp->att, G_STRIP | G_UP_FIRST_CHAR | G_ARROW, 6, wnp); `co(10,1);/// set_validation_func`co(); `keyword(source,[UW_ENTRY.C]~set_validation_func); Allows you to set your own data entry validation function that is called every time a character is typed in `keyword(wn_gets_ll,/// wn_gets_ll);. Note that this is not necessarily called for every keystroke. If the user pressed the arrow keys, backspace, etc. the function will not be called. It is called only when entering data. (If you wish to process every keystroke, see `keyword(set_gets_hook,/// set_gets_hook);.) When the function is called it is passed a series of parameters that allow complete flexibility. The validation routine should return a 1 if all's well, else it should return a 0. If 0 is returned, the entry routine will overwrite the invalid character with the mask character for the current position. See the demo program `keyword(str_demo,[STR_DEMO.C]main); for more details. Prototype: void set_validation_func( int (*func_ptr)(char*, char*, char*, int, int, WINDOW*) ); Parameters: `co(11,1); int (*func_ptr)(char*, char*, char*, int, int, WINDOW*)`co(); A function pointer which is called for each character entry. Usage: set_validation_func( date_vld ); ... int date_vld( char *w, char *t, char *m, int pos, int max_pos, WINDOW *wnp ) { /* w - pointer to current work string */ /* m - pointer to the mask */ /* t - pointer to the template */ /* pos - current cursor position */ /* max_pos - maximum cursor position */ /* wnp - pointer to the entry window (use for err msg, etc) */ } `co(10,1);/// set_gets_hook`co(); `keyword(source,[UW_ENTRY.C]~set_gets_hook); Allows you to set your own hook to be called from `keyword(wn_gets_ll,/// wn_gets_ll);. Your hook will be called on entry, exit, and every time a key is pressed. Wn_gets_ll will call your function, passing the work string, template, mask, cursor position, maximum cursor position, the process type, a pointer to the global Event, and the window pointer for the entry. NOTE: The process type can be one of the three defines ( in UW.H ) H_ENTRY, H_EXIT, or H_PROCESS. Wn_gets_ll calls your hook on function entry, exit, and every time a key is pressed. You may modify any of the strings passed, or even modify the key value. If you wish to modify the key, simply set event->key inside your routine. This will allow you to remap any of the keys used in the entry routine to ones you might like more. Prototype: void set_gets_hook( int (*func_ptr)(char*, char*, char*, int, int, int, EVENT*, WINDOW*) ); Parameters: `co(11,1); int (*func_ptr)(char*, char*, char*, int, int, int, EVENT*, WINDOW*)`co(); A pointer to the function to call. Usage: set_gets_hook( super_hook ); ... int super_hook( char *w, char *t, char *m, int pos, int max_pos, int proc_type, EVENT *event, WINDOW *wnp ); { /* w - pointer to current work string */ /* t - pointer to the template */ /* m - pointer to the mask */ /* pos - current cursor position */ /* max_pos - maximum cursor position */ /* proc_type - defines H_ENTRY, H_EXIT or H_PROCESS */ /* event - pointer to the global Event variable */ /* wnp - pointer to the entry window (use for err msg, etc) */ } `co(4,7);───────────────────────────── /// Menuing ────────────────────────────────────`co(); ┌──────────────────────────────────────────────────────────────────────────┐ │ `keyword(menu_create,/// menu_create); `keyword(menu_destroy,/// menu_destroy); `keyword(menu_set,/// menu_set); │ │ `keyword(menu_restore,/// menu_restore); `keyword(item_add,/// item_add); `keyword(do_menu,/// do_menu); │ │ `keyword(menu_system,/// menu_system); │ └──────────────────────────────────────────────────────────────────────────┘ UltraWin allows both vertical and horizontal menus to be easily created and displayed for interaction with the user. The menu's entries can be selected with just one keystroke (or a simple click of the mouse). The letter to check when selecting an entry can be any character of the entry, and can even be highlighted in a different color. In addition, the menus can be defined as POPUP, restoring the area under the menu when finished, or they can be used with the window manager, forcing a redraw of overlapping areas of any windows under the menu. `co(10,1);/// menu_create`co(); `keyword(source,[UW_MENU.C]~menu_create); Initializes the menu to the specified coordinates on the screen, the menu attributes (colors), the border style and menu type passed. A call to this function must be made to define the menu before the menu is placed on the screen with menu_set. For the type parameter, use WN_POPUP if you wish the menu to be a popup menu (restoring the screen below), or WN_NORMAL if you are using UltraWin's powerful window manager. Prototype: void menu_create(int x_min, int y_min, int x_max, int y_max, int direction, uchar back_att, uchar bdr_att, uchar csr_att, uchar first_att, int bdr, int type, MENU *mnp); Parameters: `co(11,1); int x_min, y_min`co(); The upper left corner of the menu to create. `co(11,1); int x_max, y_max`co(); The lower right corner of the menu to create. `co(11,1); int direction`co(); The menu direction, use M_VERTICAL for a vertical menu and M_HORIZONTAL for a horizontal menu. `co(11,1); uchar back_att`co(); The attribute to use for the menu. This defines the color of the menu and the characters in the menu, and can be a value from 0-255. For example, use (RED << 4) | WHITE for white menu entry characters on a red background. `co(11,1); uchar bdr_att`co(); The border attribute (not used if the bdr parameter is NO_BDR). `co(11,1); uchar csr_att`co(); The attribute to use when displaying the cursor position. `co(11,1); uchar first_att`co(); The attribute to use for the menu entry selection character. Typically you would use the same background color as back_att, but a different foreground color. `co(11,1); int bdr`co(); The border style, can be either NO_BDR, SGL_BDR, DBL_BDR, SLD_BDR or DUAL_BDR (defined in uw.h). `co(11,1); int type`co(); The menu type, can be either WN_POPUP or WN_NORMAL. Use the former when not using the window manager. `co(11,1); MENU *mnp;`co(); A pointer to the menu to create. Usage: MENU mn; int back_att, bdr_att, csr_att, first_att; ... menu_create(0, 0, 20, 10, M_VERTICAL, back_att, bdr_att, csr_att, first_att, SGL_BDR, WN_NORMAL, *mn); `co(10,1);/// menu_destroy`co(); `keyword(source,[UW_MENU.C]~menu_destroy); Destroys the menu created with menu_create. The window allocated for the menu is freed. Prototype: void menu_destroy( MENU *mnp ); Parameters: `co(11,1); MENU *mnp;`co(); A pointer to the menu to destroy. Usage: MENU *mnp; ... menu_destroy(mnp); `co(10,1);/// menu_set`co(); `keyword(source,[UW_MENU.C]~menu_set); Takes a menu created with menu_create, and places it on the screen. If the menu was defined with type WN_POPUP, the area below the window is saved for later restoration. Prototype: void menu_set( MENU *mnp ); Parameters: `co(11,1); MENU *mnp;`co(); A pointer to the menu to place on the screen. Usage: MENU *mnp; ... menu_set(mnp); `co(10,1);/// menu_restore`co(); `keyword(source,[UW_MENU.C]~menu_restore); Takes a menu created with menu_create and placed on the screen with menu_set, and removes it from the screen. If the menu was defined with type WN_POPUP, the area below the window is restored. If the menu was defined with type WN_NORMAL and the window manager is in use, then the area under the menu will be redrawn. Prototype: void menu_restore( MENU *mnp ); Parameters: `co(11,1); MENU *mnp;`co(); A pointer to the menu to restore. Usage: MENU *mnp; ... menu_restore(mnp); `co(10,1);/// item_add`co(); `keyword(source,[UW_MENU.C]~item_add); Adds an entry into a menu. An integer handle (or id) that you define is passed to identify the entry. The menu_do function returns this id when the entry is selected. In addition, the index into the string for the "active" character is passed. This is the character in the string that is displayed in the first_att color upon display, and is used when a key on the keyboard is pressed that matches. Prototype: void item_add( char *entry, int id, int first_pos, MENU *mnp ); Parameters: `co(11,1); char *entry;`co(); The string to add to the menu. This string does not have to be the same length as the width of the menu, as the display routines of menu_set and menu_do justify the entry for you. `co(11,1); int id`co(); This is an id you define which will be returned to you when the menu item is selected in menu_do. `co(11,1); int first_pos`co(); This is an index into the string for the "active" letter. This letter will be used to check against keyboard letters pressed, and will be displayed in the first_att color specified in the menu_create function. For example, for the entry "Dos Shell" to make the menu_do function return the id with one keypress, use a first_pos of 4, which corresponds to the "S" in "Shell". `co(11,1); MENU *mnp;`co(); A pointer to the menu to which the item is to be added. Usage: #define DOS_SHELL 37 MENU *mnp; ... item_add("Dos Shell", DOS_SHELL, 4, mnp); `co(10,1);/// do_menu`co(); `keyword(source,[UW_MENU.C]~do_menu); Activates a menu for input from the user. Call this function after you have called menu_set. To retain flexibility, you may specify whether the do_menu function should interact with the user through the wait_event function, or immediately process the global Event variable and return to you. This gives you the ability to use your own event logic if you wish, and is useful for menus which are static on the screen, as opposed to menus that pop up and restore when finished. If interaction through wait_event is specified, then this function returns either the id of the item selected, or 0 if no item is selected. If you have do_menu only process the information in the global variable Event, then a 0 is returned for each call to do_menu that does not have an [Enter] keypress in Event. Prototype: int do_menu( MENU *mnp, int proc_mode ); Parameters: `co(11,1); MENU *mnp;`co(); A pointer to the menu for interaction. `co(11,1); int proc_mode`co(); The processing mode, which can be one of the defines M_GET_EVENT or M_PROC_EVENT. If M_GET_EVENT is used, then the menu will get input via the keyboard (or mouse if it exists) until the user has either selected one of the items, or pressed the Esc key. Usage: MENU *mnp; ... do_menu( mnp, M_GET_EVENT ); `co(10,1);/// menu_system`co(); `keyword(source,[UW_MENU.C]~menu_system); Was written specifically for the standard top menu bar with corresponding drop down menus. Menu_system gives you the option of displaying the top menu upon entry and removing the top menu upon exit (a popup menuing system), or simply use the top menu previously placed on the screen with menu_set. When called, the function will interact with the user through the keyboard and mouse, and return the menu id of the entry selected. If the Esc key was pressed or the mouse clicked off the menu, then a 0 is returned. Upon completion, the global Event variable will contain information about the last key or mouse press. NOTE: To utilize this function, you must first define your menus with menu_create, then add each entry with item_add, being sure to define a unique id for each entry. Prototype: int menu_system( MENU *top_mnp, MENU *dropmenu[], int draw_top ); Parameters: `co(11,1); MENU *top_mnp;`co(); A pointer to the vertical main menu. `co(11,1); MENU *dropmenu[];`co(); An array of pointers to a series of drop down menus. `co(11,1); int draw_top`co(); This parameter can be either 1 or 0, and specifies whether the menu_system function should handle the initial display of the top menu or assume that the top menu is already displayed. Using a value of 1 is useful if you wish your menu system to be hidden during your program, and only called up with a key. Use a 0 for when your program keeps the top menu on the screen. Usage: MENU *top_mnp; MENU *drop_mnp[8]; ... menu_system( top_mnp, drop_mnp, 1);